{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using `pymldb` Tutorial\n",
    "\n",
    "\n",
    "Interactions with MLDB occurs via a [REST API](../../../../doc#builtin/WorkingWithRest.md.html). Interacting with a REST API over HTTP from a Notebook interface can be a little bit laborious if you're using a general-purpose Python library like [`requests`](http://docs.python-requests.org/en/latest/) directly, so MLDB comes with a Python library called [`pymldb`](https://github.com/datacratic/pymldb) to ease the pain.\n",
    "\n",
    "\n",
    "## Connections\n",
    "\n",
    "The [`pymldb` library](https://github.com/datacratic/pymldb) includes a class called `Connection`. The recommended usage pattern is shown here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from pymldb import Connection\n",
    "mldb = Connection(\"http://localhost\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing the REST API\n",
    "\n",
    "Once you have a connection object, you can easily make calls to the [REST API](../../../../doc#builtin/WorkingWithRest.md.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>GET http://localhost/v1/types</strong><br /><strong style=\"color: green;\">200 OK</strong><br /> <div class=\"highlight\"><pre style=\"line-height: 125%\"><span></span>[\n",
       "  <span style=\"color: #0000dd\">&quot;datasets&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;functions&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;plugin.setups&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;plugin.startups&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;plugins&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;procedures&quot;</span>\n",
       "]\n",
       "</pre></div>\n"
      ],
      "text/plain": [
       "<Response [200]>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mldb.get(\"/v1/types\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>GET http://localhost/v1/types?x=y</strong><br /><strong style=\"color: green;\">200 OK</strong><br /> <div class=\"highlight\"><pre style=\"line-height: 125%\"><span></span>[\n",
       "  <span style=\"color: #0000dd\">&quot;datasets&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;functions&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;plugin.setups&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;plugin.startups&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;plugins&quot;</span>, \n",
       "  <span style=\"color: #0000dd\">&quot;procedures&quot;</span>\n",
       "]\n",
       "</pre></div>\n"
      ],
      "text/plain": [
       "<Response [200]>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#keyword arguments to get() are appended to the GET query string\n",
    "\n",
    "mldb.get(\"/v1/types\", x=\"y\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>PUT http://localhost/v1/datasets/sample</strong><br /><strong style=\"color: green;\">201 Created</strong><br /> <div class=\"highlight\"><pre style=\"line-height: 125%\"><span></span>{\n",
       "  <span style=\"color: #333333; font-weight: bold\">&quot;status&quot;</span>: {\n",
       "    <span style=\"color: #333333; font-weight: bold\">&quot;columnCount&quot;</span>: <span style=\"color: #0000dd\">0</span>, \n",
       "    <span style=\"color: #333333; font-weight: bold\">&quot;rowCount&quot;</span>: <span style=\"color: #0000dd\">0</span>, \n",
       "    <span style=\"color: #333333; font-weight: bold\">&quot;valueCount&quot;</span>: <span style=\"color: #0000dd\">0</span>\n",
       "  }, \n",
       "  <span style=\"color: #333333; font-weight: bold\">&quot;config&quot;</span>: {\n",
       "    <span style=\"color: #333333; font-weight: bold\">&quot;type&quot;</span>: <span style=\"color: #0000dd\">&quot;sparse.mutable&quot;</span>, \n",
       "    <span style=\"color: #333333; font-weight: bold\">&quot;id&quot;</span>: <span style=\"color: #0000dd\">&quot;sample&quot;</span>\n",
       "  }, \n",
       "  <span style=\"color: #333333; font-weight: bold\">&quot;state&quot;</span>: <span style=\"color: #0000dd\">&quot;ok&quot;</span>, \n",
       "  <span style=\"color: #333333; font-weight: bold\">&quot;type&quot;</span>: <span style=\"color: #0000dd\">&quot;sparse.mutable&quot;</span>, \n",
       "  <span style=\"color: #333333; font-weight: bold\">&quot;id&quot;</span>: <span style=\"color: #0000dd\">&quot;sample&quot;</span>\n",
       "}\n",
       "</pre></div>\n"
      ],
      "text/plain": [
       "<Response [201]>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#dictionaries arguments to put() and post() are sent as JSON via PUT or POST\n",
    "\n",
    "mldb.put(\"/v1/datasets/sample\", {\"type\": \"sparse.mutable\"} ) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we create a dataset and insert two rows of two columns into it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>POST http://localhost/v1/datasets/demo/commit</strong><br /><strong style=\"color: green;\">200 OK</strong><br /> "
      ],
      "text/plain": [
       "<Response [200]>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mldb.put( \"/v1/datasets/demo\",      {\"type\":\"sparse.mutable\"})\n",
    "mldb.post(\"/v1/datasets/demo/rows\", {\"rowName\": \"first\", \"columns\":[[\"a\",1,0],[\"b\",2,0]]})\n",
    "mldb.post(\"/v1/datasets/demo/rows\", {\"rowName\": \"second\", \"columns\":[[\"a\",3,0],[\"b\",4,0]]})\n",
    "mldb.post(\"/v1/datasets/demo/commit\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "------\n",
    "\n",
    "## SQL Queries\n",
    "\n",
    "Now that we have a dataset, we can use the `query()` method on the connection to run an [SQL query](../../../../doc/#builtin/sql/Sql.md.html) and get the results back as a Pandas DataFrame:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'pandas.core.frame.DataFrame'>\n"
     ]
    }
   ],
   "source": [
    "df = mldb.query(\"select * from demo\")\n",
    "print type(df)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>a</th>\n",
       "      <th>b</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>_rowName</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>second</th>\n",
       "      <td>3</td>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>first</th>\n",
       "      <td>1</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "          a  b\n",
       "_rowName      \n",
       "second    3  4\n",
       "first     1  2"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Where to next?\n",
    "\n",
    "Check out the other [Tutorials and Demos](../../../../doc/#builtin/Demos.md.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
